Pascal Super Library

home *** CD-ROM | disk | FTP | other *** search

/ Pascal Super Library / Pascal Super Library (CW International)(1997).bin / TURB_VIS / TVDMX / README.DOC < prev next >

Wrap

Text File | 1994-06-20 | 51KB | 1,301 lines

tvDMX (c) 1992,94 Randolph Beck ===== ░░░░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░░ ░░░ ░░ ░░ ░░░░░ ░░ ░░ ░░ ░░ ░░░░ ░░░░ ░░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░░ ░░ ░░░ ░░ ░░░ ░░ ░░ ░░ ░ ░░ ░░ ░░ ░░ ░ ░░░░░░ ░░ ░░ ░░ ░░ tvDMX is an object-oriented data entry platform for Turbo Vision with a mechanism to create scrolling forms, spreadsheets and tables. REGISTRATION AND LICENSING ========================== This is a shareware product and may be copied for free --providing that it is not altered and is transferred with its documentation. Its registration policy is as follows: * The registration fee is $20 per programmer, or $50 for a site license. There is no run-time fee for a program compiled with tvDMX code. * tvDMX may be used only for development of compiled programs. The source code may not be sold, except as described in the VENDOR.DOC file. * Previously registered programmers do not need to re-register to use this version. * Registered users will receive a diskette with the most recent version of tvDMX with additional units and programs. Registered users are entitled to support via mail or CompuServe. The author may be contacted at this address: Randolph Beck tvDMX Registration P.O. Box 56-0487 Orlando, FL 32856-0487 CompuServe: 72361,753 Page ii Table of Contents ----------------- tvDMX OVERVIEW ............................................ 1 Keystroke Philosophy ................................. 1 tvDMX CONCEPTS ............................................ 2 The Data-Formatting Template ......................... 2 USING tvDMX IN YOUR PROGRAMS .............................. 3 Data Windows ......................................... 3 Automatic Assignment Constructors .................... 4 Loading tvDMX Views from a Stream .................... 4 USING tvDMX FOR SINGLE FIELD EDITORS ...................... 5 CREATING FORMS WITH tvDMX ................................. 6 Initialization Parameters ............................ 6 Sample Form .......................................... 7 Function EntryBox() .................................. 8 ADVANCED FEATURES ......................................... 9 User Key Errors ...................................... 9 Hidden and Read-Only Fields .......................... 9 Swapping Field Positions ............................. 9 REFERENCE ................................................ 10 Object Hierarchy .................................... 10 Units ............................................... 11 Data Template Codes ................................. 12 USING TEMPLATE CODES ..................................... 13 Template Control Codes .............................. 16 Field Descriptor Functions .......................... 18 FYI ...................................................... 19 Important Virtual Methods ........................... 19 External Database Access ............................ 20 Global Functions in Units DMXGIZMA and tvGIZMA ...... 21 INVOICE .................................................. 22 tvDMX OVERVIEW Page 1 ============== This project was originally undertaken to enable programmers to quickly design data entry screens which users could operate in a natural and intuitive way. Earlier designs of tvDMX could edit data in a browse format. The newest derivative objects work as regular data-entry forms. The object-oriented framework of tvDMX can be extended to access any type of data structure (including files, Streams and Collections). tvDMX display formats use picture templates and grant the programmer full control over the appearance of each field. Features: * programmable display formats for the major Pascal data types * containment within a scrolling Turbo Vision view * record structure and display format can be set at run-time * hidden and read-only fields * field display position order can differ from physical order * reports can be generated for the data in views * support for browse and vertical record display formats This document should give a quick introduction to tvDMX. Rather than detail the inner workings, you may prefer to review several of the instructive samples: SAMPLES.PAS displays several windows: Each has data in various formats. This will give you an idea of what tvDMX can do. FORMSHOP.PAS demonstrates create form-style data entry windows. WORKSHOP.PAS is intended for your own experiments. It uses the simplest type of data window. FILESHOP.PAS manages data on disk via a TDosStream object --to show that tvDMX operations are not limited to data in RAM. FILEDEMO.PAS also manages data on disk, but it has been customized to use a standard Pascal file. COLLECTR.PAS demonstrates how to edit data in a collection. The source code for each of these programs contains additional information about its use and features. Keystroke Philosophy -------------------- Most keys work as you would expect. In addition: kbCtrlT deletes the current field, and kbCtrlY deletes the current record. The kbLeft and kbRight keys normally move the field pointer from one field to another. Movement within a character field is permitted: 1) After a character is entered into the field; 2) after kbIns, kbCtrlT or kbCtrlY is pressed; or 3) anytime the keyboard is not in INSERT mode. tvDMX CONCEPTS Page 2 ============== The Data-Formatting Template ---------------------------- The default appearance of these views is usually column/row oriented, with the exception of form-like views and single fields. You declare a record structure for the DMX initialization procedure in a template string --which also determines the display format. (You will see later how tvDMX can be used to work with forms or field editors.) A RECORD of STRING [20], INTEGER, and REAL may use this format: ' ssssssssssssssssssss | iiii |($rrr,rrr.rr)' And that would present a records in this way: │ Ace Exchange Network │ 154 │ $ 12,056.55 │ │ CommCheck, Inc. │ -28 │($ 725.00)│ The template string in this example was entirely in lower case. If in upper case, character-fields would be entered in upper case and numeric-fields would be restricted to positive values. The data TYPE of each field is determined by the characters in the string. All primary Pascal data types are supported: BOOLEAN, BYTE, SHORTINT, INTEGER, LONGINT, WORD, STRING, CHAR, arrays of CHAR, and REAL. The programmer only needs to alter this one template string when changing the data structure. (Template codes are listed on the Reference page.) You can switch to SINGLE, DOUBLE or EXTENDED reals by changing TYPE TREALNUM in RSET.PAS. A backslash ('\') may be used as a field delimiter, and is displayed as a space character. (Other delimiters can be devised as well --please refer to the ^D control code.) The tilde ('~') character can be used to switch format-processing on and off. This makes it possible to separate the text-literals from format and control codes: ' ~Name:~ ssssssssssssssssssss\ ~SSN:~ ###-##-#### ' This is diplayed as: ' Name: Abigail Adams SSN: 012-34-5678 ' String fields can now be abbreviated with the '`' character (the backward apostrophe) so that long strings don't take so much space on the screen. While editing, users can scroll within the field. Example: ' ssssssssssssssssssss`ssssssssssssssssssss| ww,www ' This will be displayed like this: ' International Busin>| 1,024 ' The '>' would actually be an arrow character. USING tvDMX IN YOUR PROGRAMS Page 3 ============================ Data Windows ------------ Presumably you understand that a focused TScroller is owned by, and operates within, an active TWindow. The TScroller also has several peer-views: a TFrame and two TScrollBars. If you wished, you could add more views to display additional information. This is how the TDmxScroller object works, as well as its descendant TDmxEditor. (A TDmxScroller object displays data in a scrolling window. TDmxEditor --its first descendant-- adds the ability to edit the data.) Programmers can instantiate a TWindow view and insert a TDmxEditor object just like using TScroller --with a few extra parameters. Then, for an effective data window, field titles should be placed at the top, and a record number indicator should be placed below.* The TDmxWindow object (a descendant of TWindow and tvGIZMA's TLtdWindow) coordinates the entire process of inserting these extra views. Initialization Syntax: constructor TDmxWindow.Init( var Bounds : TRect; ATitle : TTitleStr; ANumber : Integer; ATemplate : String; var AData; BSize : Longint; var ALabels : String; IndLen : Integer); Bounds, ATitle and ANumber are the same parameters required for any TWindow object. ATemplate is a tvDMX data format template string. AData refers to the data to be edited. Note that your data is not part of this object. BSize is the size of the entire data structure. ALabels is the string which labels the fields over the editor. IndLen is the length of a record number indicator view (usually about five to ten characters). The default indicator is placed just to the left of the horizontal scroll bar. The TDmxWindow.Init() constructor will first assign and construct two auxiliary views, TDmxLabels and TDmxRecInd, which serve as a field title display and a record number indicator. This process is managed by virtual methods in object TDmxWindow which may be overridden with new descendants. *See WORKSHOP.PAS for an example of how to use tvDMX with TWindow types. Automatic Assignment Constructors Page 4 --------------------------------- Programmers who make extensive use of tvDMX descendants may which to avoid using TDmxWindow objects and insert TDmxEditor views directly into TWindow or TDialog window types. Automatic assignment constructors were developed to make this process easier. TDmxLabels and TDmxRecInd object types can use alternate constructors: constructor TDmxLabels.InitInsert(AOwner: PGroup; var ALabels ); ALabels refers to the String that displays field heading labels. constructor TDmxRecInd.InitInsert(AOwner: PGroup; Len: integer); Len refers to the desired width of the indicator view. Both require a pointer to the window that it will be inserted into. They can use the size of that view to assign and position themselves. The view insertion is also automatic. WORKSHOP.PAS uses automatic insertion constructors with a regular TWindow object. Loading tvDMX Views from a Stream --------------------------------- tvDMX objects have Load() constructors and Store() destructors that load and store the object's fields. But it would be impractical for the tvDMX object to also retain the window's database because the data source can vary, depending upon the application. Therefore, two virtual methods should be overridden for storage on streams: procedure LoadData(var S: TStream); VIRTUAL; procedure StoreData(var S: TStream); VIRTUAL; LoadData() must set Pointer WorkingData with the address of the database and set Longint DataBlockSize with the size of the database (in bytes, not records). It should be designed in a way that allows for the possibility that the database may have been removed or altered by another program since the time this object was stored. StoreData() must save the database parameters in a way that it may be reopened by LoadData(). Note: The LoadData() and StoreData() methods for object TInputFields are already implemented, since their small amount of data are easily streamed. USING tvDMX FOR SINGLE FIELD EDITORS Page 5 ==================================== It is only natural that a descendant of TDmxEditor would be written to serve as a replacement for the TInputLine object. Object TInputFields is a TDmxEditor derivative that: 1) Allocates memory to hold the data fields; 2) Overrides the DataSize(), GetData() and SetData() methods; 3) Uses a different palette suitable for Dialog boxes; and 4) Has special handling of the cursor keys to operate more naturally within a Dialog box. A special insertion function was written to measure and initialize it with an accompanying TLabel object: function InsertField(Dialog: PDialog; Col,Row: Integer; Fmt: Boolean; ALabel,ATemplate: String) : PView; Dialog is a pointer to the dialog window into which these views are inserted. Col and Row are the upper left corner of the label. Fmt orientation of the tvDMX editor view, relative to the label: If TRUE, then the editor view is below the label; but if FALSE, the editor view follows the label on same line. ALabel is the string that will become the label. ATemplate is the string that becomes the editor view. This function returns a pointer to the TInputFields view. Usually, the pointer will be discarded (this unit is compiled with extended syntax so that the function can be implemented as a procedure), but there will be occasions when the pointer is needed. Examples: InsertField(Dialog, 5,2, TRUE, '~N~ame', 'SSSSSSSSSSSSSSSSSSSS'); InsertField(Dialog, 5,5, FALSE, '~S~SN: ', '###-##-####')^.HelpCtx := hcSSN; P := InsertField(Dialog, 5,6, FALSE, '', '$rrr,rrr.rr '); { note that the label is optional } The "Accounts" dialog in SAMPLES.PAS demonstrates the use and operation of the InsertField() function. See the next page for information on how to use tvDMX for entire forms. CREATING FORMS WITH tvDMX Page 6 ========================= tvDMX views are not restricted to rows and columns. The views in unit DMXFORMS edit data like a form. Forms can be created by chaining TSItem strings, and the leading PSItem pointer (which represents the top line) is passed to the new tvDMX object's constructor. There are actually two new object types: TDmxForm and its descendant TDmxDlgForm (which is used in dialog boxes). This is the syntax for the two constructors: TDmxForm.Init(ATemplates: PSItem; AInScroll: boolean; var AData; var Bounds: TRect; ALabels,ARecInd: PDmxLink; AHScrollBar,AVScrollBar: PScrollBar); TDmxDlgForm.Init(ATemplates: PSItem; var Bounds: TRect; AHScrollBar,AVScrollBar: PScrollBar); Object TDmxDlgForm overrides the GetPalette() method with a palette more suitable for a dialog box. Initialization Parameters ------------------------- ATemplates is a chain of TSItem strings. You can see how that works in the demo code in program FORMSHOP.PAS. AInScroll denotes that if FALSE, the left and right cursor keys behave as Ctrl-Left and Ctrl-Right keys when in <Ins> mode. This defaults to TRUE in TDmxDlgForm, so that parameter is not needed there. AData is the data. Object TDmxDlgForm doesn't need this parameter either because its data is stored locally within the object. It is assumed that you'd be using SetData() and GetData() in a dialog box. Bounds is the rectangle. Notice that these objects don't need the data-size because that will be inferred from the template strings. ALabels and ARecInd parameters are also not in the TDmxDlgForm object. They may be used in the same way as with object TDmxEditor. Sample Form Page 7 ----------- Type TMyRecordType = RECORD Name : string[30]; SSN : string[9]; Balance : real; Pt : pointer; Value : real; end; procedure EditForm(var AData); var R : TRect; W : PWindow; Templates : PSItem; begin Templates := NewSItem('~ Name~', NewSItem( ' \ssssssssssssssssssssssssssssss', NewSItem('', NewSItem('~ SSN: ~\###-##-####', NewSItem('~ Balance:~\($rrr,rrr.zz)', NewSItem('', NewSItem('~ Pointer:~\HHHH:HHHH', NewSItem('~ Value: ~\RRR,RRR.ZZRR ~pts~', nil))))); R.Assign(0,0, 40,14); New(W, Init(R, 'Small Form', wnNextAvail)); With W^ do begin Options := Options or ofTileable; GetExtent(R); { create new rectangle for editor object } R.Grow(-1,-1); { shrink -1 to avoid borders } Insert(New(PDmxForm, Init(Templates, { template list } MyData, { data in form } R, { view's rectangle } nil,nil, { no DmxLabels or DmxRecInd views } StandardScrollBar (sbHorizontal) StandardScrollBar (sbVertical) ) )); end; DisposeSItems(Templates); { Templates not needed after Init() } DeskTop^.Insert(W); end; As with the regular tvDMX templates, tilde symbols ('~') mark off string-literals; backslashes ('\') separate the fields; and everything else defines the field. Naturally, you need to be careful about marking these properly but it's fairly easy, and most mistakes can be found during the first test. Note: The compiler may balk at more than 20 rows of nested NewSItem() calls, but you can combine smaller sections of a form into individual functions. This is demonstrated in FORMSHOP.PAS. With scrollbars and proper segmentation, you can create huge scrollable forms. Function EntryBox() Page 8 ------------------- The TDmxDlgForm object (derived from TDmxForm) can be used in dialog boxes. But simple dialog boxes can easily be created using tvDMX's new EntryBox() function. function EntryBox(Title : string; AData : pointer; AOptions : word; AForm : PSItem) : word; Title is used as the title of the dialog box. AData is a pointer to the data to be edited. EntryBox creates its own temporary data buffer, used during the editing process, and does not transfer the data back if a cmCancel command is generated. You may use NIL to test the dialog box if you have no data yet. AOptions uses mfXXXX codes like those from TV's standard MessageBox() function. It then and adds corresponding buttons to the dialog box. There are also three new mfXXXX codes: mfHelpButton --adds a help button to the dialog box; mfViewOnly --prevents the user from editing the data; mfDefault --makes the OK button the default selection. AForm is a PSItem pointer to the first row in the template chain. Example: procedure EditEmployeeRecord(RecNum: longint); var Control : word; EmpRec : EmployeeRecordType; begin GetRecord(EmpRec, RecNum); Control := EntryBox('Employee', @EmpRec, mfOKCancel + mfDefault, NewSItem('', NewSItem('~ Name~', NewSItem( ' \ssssssssssssssssssss\ ', NewSItem('', NewSItem('~ ID Number:~\ ZZZW ', NewSItem('', NewSItem('~ Earnings:~\($rrr,rrr.zz)', NewSItem('', nil)))))))) ); If (Control = cmOK) then UpdateRecord(EmpRec, RecNum); end; The dialog box is automatically sized and centered. Horizontal and vertical scrollbars are added only if necessary. Remember to split large forms (20 or more rows of NewSItem calls) into smaller sections as demonstrated by the large forms in FORMSHOP.PAS. ADVANCED FEATURES Page 9 ================= User Key Errors --------------- Keys pressed that are out of range (eg: 'z' within numeric fields) will generate cmDMX_WrongKey command events. See tvGIZMA.PAS for examples. Hidden and Read-Only Fields --------------------------- Some programs use data with hidden fields. (dBASE files require a leading byte at the beginning of each record.) And many programs use fields which can be seen but not altered. (This may be when the field is accessed by the program and not by the user.) Both of these situations are handled by control codes in the template string that mark fields as Hidden or Read-Only. Example: ^H + 'B' + #0 + ^R + ' iii |'... ^H + 'B' specifies a hidden BYTE field; #0 marks a new field without a visible delimiter; ^R marks the next field as a Read-Only integer; and so on... Program users will recognize Read-Only fields because they have their own color in the palette (when focused). Swapping Field Positions ------------------------ Date fields are often arranged in Year-Month-Day order, but the conventional display format is Month-Day-Year. The ^P control code makes it possible to display and edit fields in a different order than in which they are physically organized. This exchange is transparent to the user. Unit DMXGIZMA contains fldDATE, a string constant that uses the ^P code to display and edit a three-word date field. Here is how it works: CONST fldDATE = ' WW-'^F^Z + ^U+char(12) + ^P+char(2) + #0'ZW-'^Z + ^U+char(31) + #0'ZZZW '^Z^F + ^P+char(-6) + #0 + ^P+char(4); fldDATE defines what is called a "complex field". The ^F control code ensures that these three integer fields receive the same field number. The ^P code uses the next character to adjust the data pointer forward 2 bytes, backward 6 bytes, and then 4 bytes forward again. This way, the YEAR-MONTH-DAY field can be displayed and edited in MONTH-DAY-YEAR order, like this: ' 1-01-1992 '. The ^U code is used to denote an upper limit for each field. Refer to the section on control codes elsewhere in the documentation. These advanced features are demonstrated in program SAMPLES.PAS. REFERENCE Page 10 ========= Object Hierarchy ---------------- TObject (OBJECTS.TPU) | TView (VIEWS.TPU) | TScroller (TVIEWS.TPU) | | TDmxScroller (TVDMX.PAS) | | | +--TDmxCollectView (TVDMXCOL.PAS) | | TDmxEditor (TVDMX.PAS) | | |--TDmxCollector (TVDMXCOL.PAS) | | |--TDmxEditBuf (TVDMXBUF.PAS) | | | +--TDmxStreamBuf | | | | | +--TDmxExpBuf | | | +--TDmxPxEditor // registered version only | | | +--TDmxParadox // registered version only | | |--TDmxEditDlg (STDDMX.PAS) | | | +--TInputFields | | +--TDmxForm (DMXFORMS.PAS) | +--TDmxDlgForm Units Page 11 ----- Unit RSET contains untyped constants and data types. No objects, procedures, functions, or typed-constants are included. Unit DMXGIZMA has a formatting function used internally by tvDMX and defines the DMX-specific constants and types; Unit tvGIZMA has several objects and functions for Turbo Vision support which includes TAppA --an advanced application view; Unit tvDMX contains: object TDmxScroller --a data scroller object object TDmxEditor --a data editor derived from TDmxScroller object TDmxRecNum --a view which displays the record number objects TDmxExtLabels, TDmxLabels, TDmxFLabels and TDmxMLabels --views which displays text (used for field titles) Unit StdDMX contains: object TDmxEditDlg --TDmxEditor derivative for dialog boxes object TInputFields --TInputLine replacement for all data types object TDmxViewer --TWindow descendant that initializes and INSERTs a TDmxScroller object object TDmxWindow --TDmxViewer descendant that initializes and INSERTs a TDmxEditor object Unit tvDMXCOL contains: object TDmxCollector --TDmxEditor derivative for collections object TDmxCollectorWin is a TDmxWindow derivative for TDmxCollector Unit tvDMXBUF contains buffered tvDMX objects: object TDmxEditBuf --TDmxEditor derivative for external data object TDmxStreamBuf --TDmxEditBuf derivative for stream data object TDmxExpBuf --descendant of TDmxStreamBuf that expands as records are appended (see FILESHOP) objects TDmxBufWin and TDmxExpBufWin --TDmxWindow descendants for control of the previous two objects; Unit DMXFORMS contains objects to build forms: object TDmxForm --main TDmxEditor forms object object TDmxDlgForm --TDmxForm derivative for dialog boxes proc MakeEntryBox() --creates a form in a dialog box func EntryBox() --uses MakeEntryBox to display a form Unit tvDMXREP contains objects that output listings of tvDMX data. Read file DMXUTILS.DOC for detailed information. Data Template Codes Page 12 ------------------- Field codes: 'S' --STRING field '#' --STRING field (numbers only) 'C' --CHARacter field (can be used for CHAR arrays) '0' --CHARacter field (numbers only) 'X' --BOOLEAN value field 'B' --BYTE field 'J' --SHORTINT field 'W' --WORD field 'I' --INTEGER field 'L' --LONGINT field 'R' --REAL number field (uses TYPE TREALNUM in RSET.PAS) 'N' --dBASE-formatted numeric CHAR field 'H' --HEXadecimal numeric entry 'K' --BIT CLUSTER field ('K'=CheckBox; 'k'=RadioButton) Field code modifier: 'Z' --zero modifier to force leading or trailing zeroes Field control codes: ^A --show all zero values in all fields ^C --use the next character as a field access code ^D --use the next character as a field delimiter ^F --start/end complex field ^H --hidden field ^P --display position modifier ^R --read-only field ^S --"skip" field (cursor will skip over it) ^U --set field's upperlimit (1 to 255 only) ^V --set field's default value ^X --special BOOLEAN field ^Z --show zeroes if this field is empty '~' --switch string-literals on/off Field delimiters: #0 --technical field delimiter (not displayed) '\' --displayed as a space '|' --displayed as a solid vertical line (#179) #179 or #186 may also be used as delimiters Template extension functions: (in file DMXGIZMA.PAS) func InitAppendFields() func InitBlobField() func InitEnumField() func InitTSItemFields() USING TEMPLATE CODES Page 13 ==================== STRING Fields: 's' regular STRING field 'S' STRING field (forces upper case) '#' STRING field (numbers only) These codes are used for normal Turbo Pascal STRING types. If the '#' code is used then only spaces or numeric characters ('0'..'9') can be entered. Examples: 'ssssssssssssssssssss' '~Name:~ SSSSSSSSSSSSSSSSSSSS' ' ###-##-#### ' CHAR Fields: 'c' CHAR field 'C' CHAR field (forces upper case) '0' CHAR field (numbers only) Editing keys will operate in the same manner as STRING fields when the field contains more than one character. (Use these codes for dBASE file structures.) If the '0' code is used then only spaces or numeric characters ('0'..'9') can be entered. Examples: 'C' 'cccccccccccccccccccc' '~Name:~ CCCCCCCCCCCCCCCCCCCC' ' 000-00-0000 ' BOOLEAN Fields: 'X' regular BOOLEAN field ^X indicates special BOOLEAN field A regular BOOLEAN field will display the character ShowTRUE (as defined in unit DMXGIZMA) or ShowFALSE, depending upon the value of that field. A special BOOLEAN field has no indicator of its own, but will display the template only if the data is TRUE. Examples: 'X' '[X]' '~TRUE~' + ^X Page 14 INTEGER Fields: 'B' BYTE field 'J' SHORTINT field 'W' WORD field 'I' INTEGER field 'L' LONGINT field 'Z' ZERO modifier to display leading zeroes The value of each field is limited to the natural limit of its field TYPE, regardless of the displayed width of its template. Upper case codes signify that negative numbers are not permitted. (Case is not relevant for BYTE and WORD fields.) The 'Z' modifier can be used to force the display of a leading zero as long as the data type is in one of the template characters. Examples: 'BBB' 'WWWWW' 'ZZZZW' 'ii,iii' '%WZW' 'LLL,LLL,LLL' REAL Number Fields: 'R' REAL number field REAL numbers are declared like other numeric fields except that parentheses '('/')' can be used to enclose the template. These will be displayed only if the value is a negative number. Floating point numbers other than of TYPE REAL can be used if TYPE TREALNUM is changed in RSET.PAS. (See RSET.PAS.) New in version 2.0: Trailing zeroes will not be displayed unless 'z' was used in the template. Examples: '($rrr,rrr.zz)' 'rr,rrr.zrrr' 'RRRRR.RRR' Hexadecimal Fields: 'H' Hexadecimal numeric field Used for displaying and editing data in hexadecimal formats. The size and type of the field is dependent upon the number of H's. This code is used extensively in unit tvDMXHEX.PAS. Examples: 'HH' 'HHHH' 'HHHH:HHHH' Page 15 dBASE-formatted numeric CHAR Fields: 'N' Numeric character field These fields are stored as character arrays but are edited like the numeric fields. This may be formatted like any numeric field except that parentheses cannot be used. dBASE date fields can be formatted using 'Z' modifiers and a system of ^P codes. (See fldNDATE in FILESHOP.PAS.) Examples: 'nnn' 'ZZN' '$nnn,nnn.zz' BIT-CLUSTER Fields: 'K' + CHAR CheckBox bit field 'k' + CHAR RadioButton bit field Cluster fields emulate Turbo Vision's TCluster views within a tvDMX scroller. They were originally intended for form-views, but they can be used in any type of tvDMX object. The 'K' or 'k' template code is followed by another character that designates which cluster it belongs to. It does not matter what this character is, as long as each cluster has its own. Examples: NewSItem(' [KA] ~Box 1 ~\ (kB) ~Button 1 ~', NewSItem(' [KA] ~Box 2 ~\ (kB) ~Button 2 ~', NewSItem(' [KA] ~Box 3 ~\ (kB) ~Button 3 ~', NewSItem(' [KA] ~Box 4 ~\ (kB) ~Button 4 ~', nil))) These examples use a cluster of checkboxes identified as bank 'A', and a cluster of radiobuttons identified as bank 'B' The brackets and parentheses are not significant and may be substituted. The 'A' and 'B' cluster-ID's are not displayed. By default, each cluster-group holds one WORD-type of data. So, there can be up to 16 controls for each RadioButton-cluster. This can be changed to a LONGINT type by setting SizeOfFldCluster := 4; Template Control Codes Page 16 ---------------------- Switch to Literals: '~' Switches DMX template interpretation to codes or literals. This permits static-text to be used in a template string. Examples: '~Name:~ SSSSSSSSSSSSSSSSSSSS' '$RR,RRR.RR ~CR~' String/Character Field Contraction: '`' Shortens the visible portion of a string field. Only the portion of the template before the '`' marker will be displayed. The remainder can be seen and edited by scrolling (within the field) to the right. Examples: '~Name:~ SSSSSSSSSSSSSSSSSSSS`SSSSSSSSSSSSSSS' ' cccccccccc`cccccccccccccccccccc' Special Field Attributes: ^A show zeroes in all fields ^C' use the next character as a field access code ^H Hidden field ^R Read-Only field ^S Skip field (cursor will skip over it) ^Z show zeroes if this field is empty Every field has its own field-access attribute. They may be combined as needed. ^A will function as though was set ^Z for each field. ^C+char(accSpecA) sets the accSpecA flag for that field. (accSpecA, accSpecB and accSpecC flags are available for your own custom use.) Note that Hidden or Skip fields can still be zeroized when the record is zeroized, unless it is also marked as Read-Only. Define Template Delimiter: ^D + CHAR Uses the following character as a field delimiter. Examples: ' WW' + ^D+'-WW' + ^D'-WWWW ' ^D + #255 Page 17 Start/End Complex Field: ^F Begins or ends a complex field. Each individual field within a complex field group is given the same field number. Example: ^F + ' BB | BB | WWWW ' + ^F Position Modifier: ^P + CHAR Sets the position within the record (and also the record size) to another point relative to the number of bytes indicated by the SHORTINT value of the following character. This is used by the fldDATE constant to swap the diplay positions of a date record from Year-Month-Day to Month-Day-Year. Examples: ^P + char(20) ^P + char(-4) Set Field Upper Limit: ^U + CHAR The next character will be the field's upper limit (up to 255). This is used by fldDATE to limit months to 12 and days to 31. Example: ^U + char(12) Set Field Default Value: ^V + CHAR The following character will be the field's default value, which is set when it is zeroized. Normally this would be zero for numerics and spaces for character fields. Example: ^V + '0' Field Descriptor Functions Page 18 -------------------------- Some situations require special functions that assign control codes. The following functions return DmxIDstr strings (which are STRING[8] types) that have the required control codes. function InitAppendFields(ATemplate: pstring) : DmxIDstr; Initializes a pointer to more field templates. This can be used to increase the effective length of your template. You can also use function InitTSItemFields() to extend template strings. Example: Stx2 := 'WW,WWW |WW,WWW | CCCCCCCC '; Stx1 := ' sssssssssssssss|WW,WWW |' + InitAppendFields (@Stx2); function InitBlobField(Len: integer; AccMode,Default: byte) : DmxIDstr; Initializes an unformatted data field of the given field length. BLOb fields take space within the record but will not be displayed. Use procedure GetBlob() in unit STDDMX.PAS to retrieve this data. Example: Stx := ' sssssssssssssss|WW,WWW | CCCCCCCC ' + InitBlobField (20, AccNormal, 0); function InitEnumField(ShowZ: boolean; AccMode,Default: byte; AItems: PSItem) : DmxIDstr; Initializes a tvDMX enumerated field list. Example: Stx := ' sssssssssssssss|WW,WWW |' + InitEnumField (FALSE, AccNormal, 0, NewSItem (' Zero ', NewSItem (' One', NewSItem (' Two', nil)))) + '| ###-#### |rrr,rrr.rrr '; function InitTSItemFields (ATemplates : PSItem) : DmxIDstr; Initializes a chain of TSItem templates. This can be used to increase the effective length of your template. Example: Stx := ' sssssssssssssss|WW,WWW |' + InitTSItemFields(NewSItem(' ssssssssssssss|', NewSItem('($rrr,rrr.rr)|', NewSItem(' CCCCC|WWW,WWW ', nil)))) FYI Page 19 === Important Virtual Methods ------------------------- The following is a short list of some of the virtual methods that may be overridden or intercepted in descendant objects. Function TDmxEditor.DataAt(RecNum: integer) : pointer; VIRTUAL; Returns a pointer to the given data record. By overriding this function, a program can alter the manner in which the database is organized. This method is used exclusively for data retrieval --which allows programs to access over 64k. The objects in unit tvDMXBUF.PAS override this method to retrieve data records from external sources, but they use a buffer to store enough data to reduce delay from disk access while scrolling. The default method simply returns a pointer to the position in the database from (RecNum * RecordSize). Procedure TDmxEditor.EvaluateField; VIRTUAL; Called AFTER each FIELD is edited. It adjusts internal fields and calls DrawField() to redraw the field in the regular color. Programmers who wish to override this method should call its ancestor in the descendant object. Procedure TDmxEditor.EvaluateRecord; VIRTUAL; Called AFTER each RECORD is edited. The objects in unit tvDMXBUF override this method to return the data record to storage. Programmers who wish to override this method should call its ancestor in the descendant object. Procedure TDmxEditor.SetUpField; VIRTUAL; Called BEFORE each FIELD is edited. May call RecInd^.DrawView() if a record number indicator view is linked. Programmers who wish to override this method should call its ancestor in the descendant object. Procedure TDmxEditor.SetUpRecord; VIRTUAL; Called BEFORE each RECORD is edited. This can be intercepted to display special information (eg: record number) or to rearrange the record before editing. Programmers who wish to override this method should call its ancestor in the descendant object. External Database Access Page 20 ------------------------ TDmxEditBuf is a descendant of TDmxEditor that uses a circular buffer to edit data from a source other than in RAM. This can be overridden to access your own database library procedures, although this will not be an easy project. It retrieves each record individually when accessed. The buffer is used only for quick page draws. This object can be found in unit tvDMXBUF. It uses several abstract methods and must not be instantiated as is. Objects TDmxStreamBuf, TDmxExpBuf and TDmxPxEditor are usable descendants. Object TDmxExpBuf is demonstrated in program FILESHOP.PAS. (Object TDmxPxEditor is part of the PxDMX.PAS unit, which is issued separately.) Descendants MUST override SeekRec(), SeekEnd, ReadRec() and WriteRec(): Function TDmxEditBuf.SeekRec(RecNum: integer) : boolean; VIRTUAL; This abstract virtual method is called before reading or writing a record. It must seek to the given record position. It is important that you remember that the first record is numbered 0. It should seek to RecNum+1 if the database is structured with record number 1 as the first record. Function TDmxEditBuf.SeekEnd : boolean; VIRTUAL; This abstract virtual method must seek to the end of the database (after the last record). Since this seeks to a record that does not exist, most databases will only require that SeekEnd return TRUE. Function TDmxEditBuf.ReadRec(var RecData ) : boolean; VIRTUAL; Abstract virtual method called to retrieve record RecData. It must return a record exactly the size determined by the template. Function TDmxEditBuf.WriteRec(var RecData ) : boolean; VIRTUAL; Abstract virtual method called by EvaluateRecord() to store record RecData if a change was made. These functions must perform their record operations at the current record position and return TRUE if the operation succeeded or FALSE if it failed. It is the programmer's responsibility to retain the error code for use by the ErrorFunc() method. TDmxEditBuf.ErrorFunc() is a virtual method that may be overridden for special handling of database errors. Please refer to file tvDMXBUF for more information. Global Functions in Units DMXGIZMA and tvGIZMA Page 21 ---------------------------------------------- Procedure AssignWinRect(var Bounds: TRect; MaxX, MaxY: integer); Assigns Bounds to fit into the desktop, with MaxX and MaxY as the maximum desired width and height. Bounds is cut and moved to a cascaded position behind the currently active window. (This is similar to what happens when a new file is loaded into the TP IDE.) * Turbo Pascal 7.0 and above uses the Application^.GetTileRect() method to determine the default window bounds. Function DmxStrLen(S: string) : integer; Returns the length of the visible portions of a template string. (From unit DMXGIZMA) Not for use with forms. Function wnNextAvail : integer; Returns the next available (unused) window number. This was formerly called NextWindowNumber(). Procedure TrimDialog(Window: PWindow); Shrinks and centers a dialog window to ease the design process. The dialog window should be initialized with the maximum size allowable. TrimDialog() can be called after the controls are inserted to resize the window down to the maximum size needed. See program DLGSHOP.PAS for sample usage. TAppA = OBJECT(TApplication) TApplication extension that initializes TV's major components after saving the original user screen. Buttons and other dialog box controls in applications using TAppA will respond to UP, DOWN, RIGHT and LEFT cursor keys. It provides for handling of the cmBeep cmDMX_WrongKey, cmUserScreen, cmToggleSound, cmToggleVideo, cmCascade and cmTile command events. * Although the demo programs use derivatives of TAppA, it is not required for tvDMX. TAppPrn = OBJECT(TAppA) TAppPrn provides additional support for printing tvDMX windows (to printer or file). See the example programs. TUserScreen = OBJECT(TScroller) Scroller object that displays the original user screen that has been saved by the TAppA.Init() constructor. INVOICE Page 22 ================================================================ Remit to: From: Randolph Beck _________________________ P.O. Box 56-0487 _________________________ Orlando, FL 32856 _________________________ CIS: 72361,753 _________________________ _________________________ Contact individual _________________________ _________________________ Qty Unit Price ___ tvDMX Registration $ 20.00 ___ tvDMX Site License $ 50.00* Total _______ *Site license includes price of registration. Note that the tvDMX toolkit has been delivered and accepted by the customer. A current disk, including full documentation and more units, will be sent upon receipt of this paid invoice. Client Information (Optional) ------------------ How long have you been using Turbo Vision? _________ Which version of Turbo Pascal are you using? _______ List tools that you use: Where did you find tvDMX? [ ] AnsiView ( ) BBS_________________ [ ] Blaise: ( ) CompuServe [ ] Btrieve ( ) Internet [ ] Paradox Engine ( ) User group [ ] Topaz ( ) friend or collegue [ ] Turbo Pascal for Windows ( ) Other: [ ] TurboPower:________________ ____________________ Others: __________________________________________________ ================================================================ tvDMX 2.5